ETO Development Tools 4/ETO Development Tools 4.iso/Tools - Objects/Macintosh Programmer’s Workshop/MPW QR4/SADE 1.3b1/SADE New User WorkSheet

Text File | 1991-04-25 | 12KB | 290 lines

#    Symbolic Application Debugging Environment    1.3
#
#    Copyright Apple Computer, Inc. 1987-1990
#    All rights reserved.

###############################################################################
# This worksheet contains some commands you might like to try.
# It also contains a section on how to debug MPW tools.

###############################################################################
# Execute commands in the Worksheet as in MPW with the Enter key, or select
# menu commands from the pull-down menus on the menu bar.

Version      # To display SADE's version information; or use About SADE in Apple menu.

Help        # Get a list of help topics; or use SADE Help menu command in Find menu.

# When you compile and link your application, specify the -sym on option to create
# the file containing symbol information (.SYM) that SADE requires for debugging.

# Note that the following commands use one of the sample applications that comes
# with the SADE disk. Substitute a different sample application or one of your own
#  applications if you wish.

# Identify the target application to debug and its symbol file:
    Directory 'SADE:SADE 1.3 Tutorials:CExamples:C Tutorial 1'
#    Sourcepath 'pathname1','pathname2'    # This command is not necessary with Sample1
                                        # because its source is in one directory. Use
                                        # SourcePath only if your source files are in
                                        # multiple directories or in a different
                                        # directory than your source.
    Target 'Sample1'    # assumes symbol file is 'Sample1.SYM'

# You will see that Target not only identifies the application but launches it, opens
# the source file, and breaks at the first statement of the main program.

# Now select a statement of interest; e.g., DoMenuCommand (use the Mark menu), and
# choose the Go Til command from the SourceCmds menu. SADE sets a temporary
# breakpoint on DoMenuCommand and resumes operation of Sample1 (the traffic light
# appears). SADE will be reentered when the breakpoint is encountered; in this case,
# choose Red Light from the Traffic menu and SADE highlights DoMenuCommand in the
# source file.

# Now choose a variable to watch, e.g., gStopped, which tells whether the light is
# Red (TRUE) or green (FALSE); highlight gStopped here and select Add Watch Variable
# from the Variables menu. SADE opens a window displays its current value. SADE will
# also show its new value whenever you step.

# Now step the program using Step in the SourceCmds menu. If you want to step into a
# routine use the Step Into menu command. For example, after 4 or 5 steps you can
# step into the SetLight routine when SetLight (FrontWindow(), false); is highlighted.
# Within the SetLight routine, gStopped should change to 0.

# To remove Sample1 as the target, issue this command:
    Kill

###############################################################################
# When your application is running, you can suspend it and enter SADE by
# pressing <command-option> <SADEKey>.
# The default SADEKey is <numeric-key-pad-period>.
# To change it, modify and execute the following:

sadekey <new key code>

# See Inside Macintosh Volume 5 pages 191-192 for the key codes for the various keyboards.

###############################################################################
# Debugging Object Pascal and MacApp
    MacApp methods are supported.  Within methods, references to the instance
    variables of the object can be made without qualifying those references by SELF.
    These free references to instance variables can also be done in C++ member
    functions.

    A SADE variable, BreakIfNoSource, defaults to 0.  When 0, a Step Into will
    continue stepping until there is source statement information available for the
    instruction at the program counter.  The benefit of this is that SADE will not
    break in out-of-line arithmetic routines such as ULMODT and display mysterious
    lines of assembler.  A further benefit is that Object Pascal and MacApp method
    dispatches are treated as indivisible operations: stepping into a method call
    will break at the first instruction of the method, without the necessity of
    fiddling around with StepMethod procedures and what not.  The down side
    (there's always a down side) is that if SADE steps into something without
    statement information, it will appear SADE has hung.  It hasn't, it's just very
    busy executing your code 2 to 3 orders of magnitude slower than normal.  This
    down side should only affect you if you compile some of your code with symbols
    and some without and then inadvertently step into it.  Should you do so, you have
    a choice of waiting for completion of stepping or rebooting.  Setting
    BreakIfNoSource to 1 will make SADE break when no source information is available
    for the PC.

    To step into a method use the StepInto menu item from the SourceCmds menu
    (Source vs Asm checked in SourceCmds) or the Step Line Into command and options.
    To avoid stepping through MacApp's method dispatch code, you should assemble
    MacApp's ≈.a files with "-SYM OFF".  Otherwise, the BreakIfNoSource switch does
    not accomplish very much.

    Follow these four simple steps when debugging MacApp code with SADE.  Assume the
    target is the MacApp sample program DemoDialogs:

    (1)    In MPW, set the directory to the location of your sourcefiles and build your
    application with symbol information:
            directory "hd:MacApp® 2.0.1:Examples:DemoDialogs:"
            mabuild -sym -autobuild DemoDialogs
    The -autobuild option will build the MacApp libraries if necessary.

    (2)    Launch SADE and set the directory to the location of the SYM file (in this
    case, DemoDialogs.SYM).  Inside the source folder, there should be a newly
    created folder named .NoDebug Sym.  This is where the SYM file will be located.
    (If you used any other mabuild option, the folder will be named differently).
    Execute the following command:
        directory "hd:MacApp® 2.0.1:Examples:DemoDialogs:.NoDebug Sym:"

    (3)    Next, you need to set the sourcepath to where your sourcefiles and the MacApp
    libraries are located.  You will need to execute the following command:
        Sourcepath    "hd:MacApp® 2.0.1:Examples:DemoDialogs:", ∂
                    "hd:MacApp® 2.0.1:Libraries:"

    (4)    Finally, you need to target your program.  You may do this either by using
    the Target menu item or by entering the Target command in the SADE worksheet:
        Target 'DemoDialogs'

    The file MDemoDialogs.cp should now be open and the program counter should be at
    the first statement: void main ()


###############################################################################
# Low-level Debugging (Set SourceCmds menu to Asm Debugging)
# If you use Step menu command now, SADE executes one instruction at a time rather
# than one source statement at a time.
# Here are some commands you can use for low-level debugging:
    Stack                        # Show the address of, owner, and caller of all
                                # stack frames

    Disasm pc 10                # Disassemble 10 instructions starting from the pc

    Disasm myProc.(1)             # Disassemble 20 (the default) instructions starting
                                # from the first statement of procedure myProc

    Dump a0 64                    # Display 64 bytes beginning at location pointed to
                                # by register a0


# Macintosh System Structures

    go til main.(9)                # or some other statement

    heap                        # Display the heap pointed at by theZone
    heap check                    # Validate the heap pointed at by theZone
    resource                       # displays all open resource maps in target application

    windowList^                    # Display FrontWindow as a grafPort
    ^WindowRecord(windowList)^    # Display FrontWindow as a windowRecord
    *(WindowRecord *)(windowList)    # doing the same with a C expression

###############################################################################
# Source Level Debugging (Set SourceCmds to Source Debugging)
# If you use Step menu command, SADE steps one source statement at a time. Here is
# a procedure for stepping a given number of times; note the use of the onEntry
# keyword, which tells SADE what to do after each step; in this case, take another
# step.
define SADELooper
SADELooper := 10
Proc StepTen
    If SADELooper > 0
        SADELooper := SADELooper - 1
        where (Δpc)
        Step onentry StepTen
    Else
        Stop
    End
End
StepTen

# To run StepTen again, remember to reset the SADELooper variable to the number
#    of steps you want.  After you're finished, you may wish to undefine SADELooper.

###############################################################################
# To remove the target application, use the following:
    kill

###############################################################################
# To debug an MPW tool (using the example tool Count):
# (1)    Compile and link the tool with symbolic information (-sym on|full)
#        Be sure to specify the file type and creator when you Link an MPW tool:
            Link -t 'MPST' -c 'MPS ' -sym on

# (2)    Launch SADE and set the directory to the location of the tool's source
#        file(s)
            Directory "hd:mpw:Examples:CExamples:"

# (3)    Target the MPW Shell using the tool's symbol file.
            Target "hd:mpw:mpw shell" using "Count.SYM"

# (4)    Then in MPW, run your tool.

# To remove the tool as the target, kill the tool using either the Kill menu
# command (which calls KillTool) or issue KillTool from the SADE worksheet.
# Do not issue the Kill command from the worksheet.  This will kill MPW.
# KillTool will shutdown the tool and leave MPW running, so you can continue to
# work in MPW if you wish.
        KillTool


###############################################################################
# The folder SadeScripts contains files with examples of the SADE language.
# You might find these interesting if you are attempting to write your own scripts.
# First, set the directory to the folder containing SadeScripts.

directory concat (SADEDir,'SADE Example Scripts:')    # SADEDir is defined in SADEStartup

# Then select any line beginning with 'execute' and press Enter; commands nested
# under the execute line can then be run as well.

execute 'DisplayMemory'
    dm windowlist^,100                    # a script that mimics the dump command


execute 'FCBChecker'
    DisplayFCBs                            # Displays information about all open files


execute 'HeapProcs'
    displayHeapInfo                        # displays various heap-related info
                                        # Execute each of these calls individually

    showfreemp                            # Displays the values of all free masterpointers
                                        # in theZone.

    heapdisplay theZone                    # mimics the heap command


execute 'MiscFunctions'                    # These show how to write functions with an
                                        # arbitrary number of arguments.
    min (5, 10)                            # Displays the minimum of 5 and 10
    max (25, 101, 67, 44)                # Displays the maximum of 25, 101, 67 and 44


execute 'MiscProcs'
    displaywindowlist                    # Displays the location and name of each open window.


execute 'ResMap'
    resmap "CODE"                        # Display information about all CODE resources.
    resmap                                # SLOWLY mimics the resource command


execute 'ResVerify'
                                        # NOTE:  The following command's validation may be too strict.
    ResVerify                            # mimics the resource check command


execute 'StackCrawl'
    StackCrawl                            # mimics the stack command


execute 'InterList Proc'
    InterList('routine name', 'output filename')    # interleaves statements and associated instructions




###############################################################################
# for the numerically minded--how many debuggers can do factorial?
# Select all of the following text and hit 'Enter'

func fact(n)
    if n <= 1.0 then
        return 1.0
    else
        return n * fact(n-1)
    end
end


proc factorial (n,file)
    define i
    if nargs>1 then
        redirect file
    end
    for i := 1 to n do
        printf("fact(%.2d) = %19.19g\n",i,fact(i))
    end
    if nargs>1 then
        redirect
    end
end


factorial (20)